package com.soccerlover9527.jadis.datasturct;

/**
 * <p></p>
 *
 * @author soccerlover9527@gmail.com
 * @since 2023-08-07
 */
public interface JString extends Lengths {
    /**
     * <p>get the sub string between begin and end index.</p>
     * <p>accept negative number which represented the offset relative to the end of string</p>
     *
     * @param begin beginning index, include.
     * @param end   end index, exclude.
     * @return sub string
     * @throws IndexOutOfBoundsException if the beginning or end index out of string length
     */
    String getRange(int begin, int end);

    /**
     * set new value and return old
     *
     * @param value new value
     * @return old value
     */
    String getSet(String value);

    /**
     * set bit value in current string
     *
     * @param bitValue  0/1
     * @param offset offset
     * @return old value
     */
    byte setBit(byte bitValue, int offset);

    /**
     * get bit value in current string
     *
     * @param offset offset
     * @return 0/1
     */
    byte getBit(int offset);

    /**
     * cover current string from offset with value.
     *
     * @param offset cover offset
     * @param value  fresh value.
     * @return new value
     * @throws IndexOutOfBoundsException if the beginIndex is negative, or larger than the length of this String object.
     */
    String setRange(int offset, String value);

    /**
     * append value to the end of the current string
     *
     * @param value appended value
     * @return The length after appending the string
     */
    int append(String value);

    /**
     * increments the current value by one
     *
     * @return new value
     * @throws NumberFormatException if the current value is not a number
     */
    long increment();

    /**
     * increments the current value by input value
     *
     * @param value addend
     * @return new value
     * @throws NumberFormatException if the current value is not a number
     */
    long incrementBy(long value);

    /**
     * decrements the current value by one
     *
     * @return new value
     * @throws NumberFormatException if the current value is not a number
     */
    long decrement();

    /**
     * decrements the current value by input value
     *
     * @param value subtrahend
     * @return new value
     * @throws NumberFormatException if the current value is not a number
     */
    long decrementBy(long value);
}
